001    /*
002     * Copyright 2005 Stephen J. McConnell
003     *
004     * Licensed  under the  Apache License,  Version 2.0  (the "License");
005     * you may not use  this file  except in  compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     *   http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed  under the  License is distributed on an "AS IS" BASIS,
012     * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
013     * implied.
014     *
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    
019    package net.dpml.library;
020    
021    import java.io.File;
022    
023    /**
024     * The Library interface is the application root for module management.
025     *
026     * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
027     * @version 1.1.0
028     */
029    public interface Library
030    {
031       /**
032        * Index filename.
033        */
034        public static final String INDEX_FILENAME = "index.xml";
035        
036       /**
037        * Utility operation to sort a collection of resources.
038        * @param resources the resources to sort
039        * @return the sorted resource array
040        */
041        Resource[] sort( Resource[] resources );
042        
043       /**
044        * Return a array of the top-level modules within the library.
045        * @return the module array
046        */
047        Module[] getModules();
048        
049       /**
050        * Return a array of all modules in the library.
051        * @return module array
052        */
053        Module[] getAllModules();
054        
055       /**
056        * Return a named module.
057        * @param ref the fully qualified module name
058        * @return the module
059        * @exception ModuleNotFoundException if the module cannot be found
060        */
061        Module getModule( String ref ) throws ModuleNotFoundException;
062        
063       /**
064        * Recursively lookup a resource using a fully qualified reference.
065        * @param ref the fully qualified resource name
066        * @return the resource instance
067        * @exception ResourceNotFoundException if the resource cannot be found
068        */
069        Resource getResource( String ref ) throws ResourceNotFoundException;
070        
071       /**
072        * <p>Select a set of resource matching a supplied a resource selection 
073        * constraint.  The constraint may contain the wildcards '**' and '*'.
074        * @param criteria the selection criteria
075        * @param sort if true the returned array will be sorted relative to dependencies
076        *   otherwise the array will be sorted alphanumerically with respect to the resource
077        *   path
078        * @return an array of resources matching the selction criteria
079        */
080        Resource[] select( String criteria, boolean sort );
081        
082       /**
083        * <p>Select a set of resource matching a supplied a resource selection 
084        * constraint.  The constraint may contain the wildcards '**' and '*'.
085        * @param local if true limit the selection to local projects
086        * @param criteria the selection criteria
087        * @param sort if true the returned array will be sorted relative to dependencies
088        *   otherwise the array will be sorted alphanumerically with respect to the resource
089        *   path
090        * @return an array of resources matching the selction criteria
091        */
092        Resource[] select( String criteria, boolean local, boolean sort );
093        
094       /**
095        * Select all local projects with a basedir equal to or depper than the supplied 
096        * directory.
097        * @param base the reference basedir
098        * @return an array of projects within or lower than the supplied basedir
099        */
100        Resource[] select( File base );
101        
102       /**
103        * Select all local projects relative to the supplied basedir.
104        * @param base the reference basedir
105        * @param self if true and the basedir resolves to a project then include the project
106        *   otherwise the project will be expluded from selection
107        * @return an array of projects relative to the basedir
108        */
109        Resource[] select( File base, boolean self );
110        
111       /**
112        * Locate a resource relative to a base directory.
113        * @param base the base directory
114        * @return a resource with a matching basedir
115        * @exception ResourceNotFoundException if resource match  relative to the supplied base
116        */
117        Resource locate( File base ) throws ResourceNotFoundException;
118        
119    }